Repository navigation
fix(control-plane): resolve checkpoint artifacts after runtime relocation - #9163
Conversation
…tion runs/index.jsonl can keep absolute json_path and markdown_path values after a runtime_root copy. Quota spend reads already remap those paths (#9161); checkpoint replay still required the stored directory to be the current runs directory, so refresh-state replay and repair rejected the copied artifact. runPath now resolves an absolute <any>/goals/<goalId>/runs/<file> path to that file name inside the current goal runs directory when the entry is a regular file, and still rejects other goals, outside paths, traversal, and non-files. Signed-off-by: Duang777 <[email protected]>
loopx-agent
left a comment
There was a problem hiding this comment.
Reviewer: model_agent · Antigravity · Google Deepmind · self_reported
动机 / Motivation
复制或迁移过 runtime_root 后触发 refresh-state 重放、回执修复或幂等结算检查点的控制面调用方与运行维护者。 此前,runs/index.jsonl 中历史记录保存了旧运行根目录下的绝对 json_path 与 markdown_path;在 #9161 已修复 quota spend 路径重映射后,checkpoint_commit.ts 的 runPath 仍强制要求路径目录严格等于当前 runsDir,导致 inspectCheckpointReplay 与 commitCheckpoint 重放阶段抛出 checkpoint artifact path is invalid 并阻断恢复。改动后,当路径满足 <任意目录>/goals/<goalId>/runs/<文件名> 且当前目标的 runs 目录下存在同名常规文件(经 realpathSync 校验未越界、非符号链接)时,改用新目录下的当前产物文件。
跨 runtime_root 拷贝后的合法 checkpoint 重放能够读取并校验新运行根目录下的同名 .json/.md 产物(而非误读旧目录残余文件);其它 Goal、越界路径、目录穿越 ..、符号链接逃逸或内部符号链接以及缺失副本仍以原有错误码与措辞拒绝。 本 PR 不改动 quota spend 读路径(#9161)、monitor_poll_commit.ts、void 交易回执、也未运行完整的 commitCheckpoint 锁交接/结算准入集成 harness(仅复用共享的 runPath 路径校验边界)。
由于此前同批已有 #9161 修复了 spend 产物读取(readQuotaSpendEventFromRun),若放任 checkpoint_commit.ts 保持硬编码目录相等检查,任何已拷贝隔离的 runtime_root 在执行 refresh-state 回放或修复时都会卡死在合法历史检查点读取上;本次小幅修补直接补齐了该缺口且具备完整可回滚边界。
改动思路 / Approach
将跨运行根目录的重定位文件名解析内聚在既有的同步控制面边界 checkpoint_commit.ts(runPath / relocatedCheckpointArtifact)中,利用同步 lstatSync/realpathSync 保持 withCheckpointHead 无异步挂起与防符号链接逃逸不变量。 当前 PR 仅修复 checkpoint_commit.ts 中 committedArtifacts 与写入共用的 runPath 校验及其单元测试并纳管 tsconfig.control-plane.json,不新增状态存储、配置开关或跨模块重构。
| 场景 | 改动前(1488ec10dd) |
改动后(a3d87641de) |
|---|---|---|
| 同目录常规文件 / 新建写入路径 | dirname(path) === resolve(runsDir) 通过 |
保持原有直通分支与 ENOENT 允许新建语义不变 |
拷贝后 <old>/goals/<goalId>/runs/<file> |
直接抛出 checkpoint artifact path is invalid |
经 relocatedCheckpointArtifact 映射至当前 realpathSync(runsDir)/<file> 并校验非符号链接常规文件 |
跨 Goal / 外部路径 / .. 穿越 |
拒绝 | 仍返回 null 并以 checkpoint artifact path is invalid 拒绝 |
| 当前目录下符号链接(外部或内部别名)或目录 | 拒绝 | lstatSync 非常规文件且 relativePath !== fileName,一律拒绝(不回退读取旧路径) |
在设计复用比较上,accounting_artifact_transaction.ts 的 readQuotaSpendEventFromRun(#9161)使用异步 fs/promises 且仅处理 .json、允许缺省返回 null;而 checkpoint_commit.ts 内部在 withCheckpointHead 临界区内要求严格同步执行(禁止 await)且同时校验 .json 与 .md 并拒绝内部符号链接。因此在既有 checkpoint_commit.ts 内保留同步的 relocatedCheckpointArtifact 助手,比跨文件引入异步接口更契合同步锁约束。
具体改动 / Changes
本次改动共涉及 3 个文件(+223 / -16):loopx/control_plane/goals/checkpoint_commit.ts(+52 / -16)、新增 tests/control_plane_ts/checkpoint_commit.test.ts(+170)以及 tsconfig.control-plane.json(+1)。
本切片无独立书面 RFC 规范(no_spec);其交付依据为本次 PR 的修复目标与 #9161 在 readQuotaSpendEventFromRun 建立的相邻路径重定位行为,并在 inspectCheckpointReplay 的实际入口与反例用例中完成对照验证。
关键代码讲解
relocatedCheckpointArtifact(loopx/control_plane/goals/checkpoint_commit.ts):校验原始路径必须为绝对路径;经resolve规范化后逐级检查父目录结构严格为.../goals/<goalId>/runs/<fileName>,且extname(fileName) === extension(排除.json类无主文件名与错误扩展名)。随后对当前runsDir取realpathSync,仅当join(runsDirReal, fileName)经lstatSync确认为常规文件、再经realpathSync计算相对路径严格等于fileName时返回规范化新路径;目录不存在或校验不符均返回null。runPath与committedArtifacts(loopx/control_plane/goals/checkpoint_commit.ts):将goalId从inspectCheckpointReplay及commitCheckpoint的回放/补充写入路径传入committedArtifacts与runPath。当路径位于当前resolve(runsDir)下时沿用既有逻辑(含新建文件尚未落盘时的ENOENT放行);仅当目录不匹配时转入relocatedCheckpointArtifact,失败则抛出原有的checkpoint artifact path is invalid(错误码checkpoint_commit_unknown)。- 单元测试套件(
tests/control_plane_ts/checkpoint_commit.test.ts):构造独立originalRoot与relocatedRoot,显式验证读取结果返回新目录路径与"relocated-runtime"字节内容(未误读旧目录"stale-original"),并覆盖缺失副本、跨 Goal、目录外路径、..穿越、外部符号链接、同目录符号链接别名及目录冒充等全部负向反例。
对主干的风险 / Risks
验证执行矩阵
- changed_invariant_positive(PASS):
npm run typecheck:control-plane(exit 0);Node TypeScript 测试覆盖checkpoint_commit.test.ts、quota_spend_commit.test.ts、vision_checkpoint.test.ts、checkpoint_read_context.test.ts、checkpoint_artifacts.test.ts、checkpoint_provider_head.test.ts、checkpoint_retention.test.ts、open_todo_semantic_checkpoint.test.ts、refresh_recovery.test.ts、vision_wait_coverage.test.ts共 121/121 通过(0 失败);Pythoninspect_checkpoint_replay经真实 TS effect runtime 跨目录迁移实测通过。 - material_negative_or_failure(PASS):实测基线
1488ec10dd的inspectCheckpointReplay在迁移目录样本上复现失败(抛出checkpoint artifact path is invalid; read back the original Turn before retrying),当前头a3d87641de通过;额外独立反例验证了.json隐式点文件名、相对路径均被拒绝,且符号链接形式的runtime_root别名可正确解析至realpath并返回对应副本;缺失目标副本时 Pythoninspect_checkpoint_replay以checkpoint_commit_unknown拒绝。 - repository_required_checks(PASS):
ruff check(tests loopx/canary loopx/control_plane loopx/domain_packs loopx/presentation)通过;scripts/check_rfc_bilingual.py通过;git diff --check干净;loopx check --scan-path扫描 3 个变更文件 0 错误 0 警告;loopx canary premerge(14 项检查:4 项直接检查、6 项目录金丝雀含semantic-vocabulary-drift-smoke.py、8 项风险特征 smoke)全部通过(0 失败)。Python checkpoint/refresh 相关套件共180 passed, 14 skipped(test_refresh_checkpoint_recovery+test_refresh_checkpoint_isolation+test_codex_checkpoint_context_refresh+test_checkpoint_provider_fence+test_checkpoint_read_context85 passed;test_research_checkpoint_capture+test_research_checkpoint_cli+test_vision_wait_coverage82 passed, 12 skipped 因未设置LOOPX_NATIVE_CHECKPOINT_BIN;test_refresh_settlement_recovery13 passed, 2 skipped 因未安装pwsh)。
风险与未覆盖边界说明
- 残余边界:
commitCheckpoint内的锁交接与写入阶段共用了同一runPath,本次测试直接覆盖inspectCheckpointReplay回放、Pythoninspect_checkpoint_replay跨语言调用及checkpoint_commit相关 TS 全套,但未构造完整多进程锁迁移的commitCheckpoint端到端重放集成测试;补充写入路径中,未落盘的新建文件(ENOENT)仍要求与resolve(runsDir)同目录,不通过重定位分支放行,且 Python 侧checkpoint_context_io.py已统一用.resolve()对齐runtime_root,不会破坏正常写入。 - 远端 CI 诊断说明:按当前
wait_for_ci=false审查策略不以远端 CI 作为充分或阻塞条件(仅作诊断附注:提交时merge_state为BEHIND,mergeable=MERGEABLE,且基线到最新origin/main之间本 PR 涉及的 3 个文件无冲突改动)。
我的整体评价 / Verdict
本 PR 属于 goal_achieved:精准解决了 runtime_root 复制后 checkpoint_commit.ts 拒绝合法历史检查点产物的问题,语义与 #9161 的 readQuotaSpendEventFromRun 对齐,且同步强化了内部符号链接防护。
- 长程与用户体验影响:
long_horizon为preserved(迁移后的运行根目录不再在refresh-state检查点回放/修复阶段卡死,同时跨 Goal 与篡改路径仍严格阻断,不触发重复扣额或状态污染);user_experience为preserved,其中visual_review为not_applicable(已核对全部 3 个变更文件仅涉及控制面 TS、单元测试与tsconfig.control-plane.json,无渲染前端或 Lark UI 变更;无未核验渲染范围unverified_scope=none)。 - 语义对齐与架构评估:不引入新共享词汇、持久化 schema 或控制面开关(
semantic_alignment为not_applicable,无共有词表扩张),架构评估为retain(同步边界内聚于checkpoint_commit.ts),兼容评估为retain(同时保留原同目录直通分支与迁移路径的常规文件检查)。全部本地 TS/Python/premerge 验证均通过,无阻塞项(merge_state=BEHIND与远端 CI 门禁由合并前流程单独检查)。
English verdict: APPROVE - exact head a3d8764 resolves relocated checkpoint artifacts inside the active goal runs directory while rejecting cross-goal, traversal, symlink, and non-file paths; local typecheck, 121 TS tests, Python boundary checks, and 14 premerge checks pass with no blocking findings.
Goal And Delivered Outcome
runtime_rootcopy,runs/index.jsonlcan keep absolutejson_path/markdown_pathvalues from the old runtime while the artifact files live at the same names under the new goalrunsdirectory. fix(control-plane): stabilize v2.4.0 explore, context, and checkpoint tail slice (Slice B4) #9161 remapped that shape for quota spend reads. Checkpoint replay still requireddirname(path) === resolve(runsDir), soinspectCheckpointReplayrejected the copied file ascheckpoint artifact path is invalid.refresh-statesettlement readback returns the raw index row. Whenrefresh_recovery.decisionisreplayorrepair_receipt,loopx/state_refresh.pycallsinspect_checkpoint_replay, which reachesrunPath. That helper now resolves an absolute<any>/goals/<goalId>/runs/<file>path to the same file name inside the current goal runs directory when that entry is a regular file and stays inside the directory afterrealpath. Other goals, outside files, traversal, symlinks, and non-files still fail closed with the existing wording.loopx-project/loopxmain.Author Declaration
Implemented against
readQuotaSpendEventFromRun).<any>/goals/<goalId>/runs/<file>to the current runs file when it is a regular file inside that directoryrunPath/relocatedCheckpointArtifactinloopx/control_plane/goals/checkpoint_commit.tstests/control_plane_ts/checkpoint_commit.test.tsrelocated-runtime casetests/control_plane_ts/quota_spend_commit.test.tsstill passessettlement_readback.tsreturnswriteback_rununmapped andstate_refresh.pypasses that row intoinspect_checkpoint_replay. Ran the new test on unmodifiedrunPathand saw it fail, then applied the helper change and re-ran the checks below. Did not run a fullcommitCheckpointsettlement-admission integration; replay and the supplement write both call this samerunPath.Scope And Continuation
runPath. In-flight monitor-poll and void transaction receipts are unchanged.Validation
a3d87641dedc8413bb36bf13dddf43f8bc3d689fregression_parityfailedthenpassednode --no-warnings --experimental-strip-types --test tests/control_plane_ts/checkpoint_commit.test.tsonmainplus the new test: 4 tests, 1 failed, 3 passed. Failure:inspectCheckpointReplay reads checkpoint artifacts copied into a relocated runtimewithcheckpoint artifact path is invalid; read back the original Turn before retrying(checkpoint_commit_unknown). The in-directory read and the outside-path / symlink / non-file rejects passed.unitpassedartifact_bytes: relocated-runtime/relocated markdown, not the stale original.unitpassednode --no-warnings --experimental-strip-types --testoncheckpoint_commit.test.ts,quota_spend_commit.test.ts,vision_checkpoint.test.ts,checkpoint_read_context.test.ts,checkpoint_artifacts.test.ts,checkpoint_provider_head.test.ts,checkpoint_retention.test.ts,open_todo_semantic_checkpoint.test.ts,refresh_recovery.test.ts,vision_wait_coverage.test.ts: 121 passed, 0 failed.staticpassednpx tsc --project tsconfig.control-plane.json --noEmit(npm run typecheck:control-plane): exit 0.staticpasseduv run --extra test python -m ruff check tests loopx/canary loopx/control_plane loopx/domain_packs loopx/presentation: all checks passed.git diff --check: clean.python scripts/check_rfc_bilingual.py --base origin/main --head HEAD: passed. No paired RFC changed.staticpassedloopx canary premerge --from-git-diff --git-diff-base origin/mainon this head:ok=true,status=passed,changed_files=3,surfaces=control_plane, direct checks 4/4, catalog canaries 6/6, risk-profile smokes 8/8, failures 0.self_merge_allowed=false.inspectCheckpointReplay→committedArtifacts→runPath), including a missing copy that must not fall back to the old file.commitCheckpointreplay and supplement write use the same helper, but this PR does not drive the settlement lock/admission harness. Monitor-poll and void receipt paths were not changed and were not re-proved beyond the existing spend suite.Frontend / Visual Evidence
Type of Change
LoopX Area
Technical Direction
Shared-authority RFC fixture impact
Boundary Checklist
.loopx/,.codex/goals/, and liveACTIVE_GOAL_STATE.md).python3 scripts/check_rfc_bilingual.py --base origin/main --head HEADpasses, or no paired RFC changed.none.Signed-off-bytrailer (git commit -s).